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The  NIST  PDES  Toolkit: 
Technical  Fundamentals 

Stephen  Nowland  Clark 


1 Introduction 

The  NIST  PDES  Toolkit  [Clark90a]  provides  a set  of  software  tools  for  manipulating 
Express  [Schenck90]  information  models  and  STEP  [Altemueller88]  product  models. 
It  is  a research-oriented  toolkit,  intended  for  use  in  a research  and  testing  environment. 
This  document  gives  a technical  introduction  to  the  Toolkit,  providing  a programmer 
with  basic  knowledge  of  its  structure.  Also  covered  are  the  mechanics  of  building  Tool- 
kit-based applications. 

In  addition  to  describing  the  structure  and  usage  of  the  Toolkit,  we  describe  three  fun- 
damental code  libraries  which  it  includes.  The  most  significant  of  these,  libmisc  . a, 
contains  various  modules  of  general  utility,  including  such  abstractions  as  linked  lists 
and  hash  tables,  libbison  . a is  a small  library  containing  support  routines  and  glo- 
bal variables  for  the  Toolkit’s  parsers.  The  third  library,  libdyna . a,  provides  a dy- 
namic (run-time)  loading  facility  for  a . out  format  object  files  under  BSD  4.2  Unix 
and  its  derivates. 

1.1  Context 

The  PDES  (Product  Data  Exchange  using  STEP)  activity  is  the  United  States’  effort  in 
support  of  the  Standard  for  the  Exchange  of  Product  Model  Data  (STEP),  an  emerging 
international  standard  for  the  interchange  of  product  data  between  various  vendors’ 
CAD/CAM  systems  and  other  manufacturing-related  software  [Smith88j.  A National 
PDES  Testbed  has  been  established  at  the  National  Institute  of  Standards  and  Technol- 
ogy to  provide  testing  and  validation  facilities  for  the  emerging  standard.  The  Testbed 
is  funded  by  the  CALS  (Computer-aided  Acquisition  and  Logistic  Support)  program  of 
the  Office  of  the  Secretary  of  Defense.  As  part  of  the  testing  effort,  NIST  is  charged 
with  providing  a software  toolkit  for  manipulating  PDES  data.  This  NIST  PDES  Tool- 
kit is  an  evolving,  research-oriented  set  of  software  tools.  This  document  is  one  of  a set 
of  reports  which  describe  various  aspects  of  the  Toolkit.  An  overview  of  the  Toolkit  is 
provided  in  [Clark90a],  along  with  references  to  the  other  documents  in  the  set. 

For  further  information  on  the  Toolkit,  or  to  obtain  a copy  of  the  software,  use  the  at- 
tached order  form. 
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1.2  Development  Environment  and  Tools 

With  the  exception  of  QDES,  the  prototype  STEP  model  editor,  implemented  in  Small- 
talk-80™ [Goldberg85],  the  NIST  PDES  Toolkit  is  implemented  in  ANSI  Standard  C 
[ANSI89].  All  software  has  been  developed  on  Sun  Microsystems  Sun-3™  and 
Sun-4™  workstations  running  the  Unix™  operating  system.  The  parsers  are  written  in 
Yacc  and  Lex,  the  standard  Unix™  languages  for  generating  parsers  and  lexical  ana- 
lyzers. The  development  compiler  for  the  Toolkit  is  GCC,  the  GNU  Project’s1 2  C com- 
piler, and  the  parsers  are  compiled  by  Bison,  the  GNU  Project’s  implementation  of 

Yacc.  The  lexical  analyzers  are  compiled  by  Flex",  a Public  Domain  implementation 
of  Lex.  Rules  for  building  the  Toolkit  are  specified  using  the  Unix  Make  utility. 

2 Structure  of  the  Toolkit 

The  NIST  PDES  Toolkit  consists  of  the  Express  [Clark90b]  and  STEP  [Clark90c] 
Working  Forms,  several  applications  which  make  use  of  these  Working  Forms,  and  the 
QDES  prototype  model  editor  [Clark90f].  The  Working  Forms  reside  in  object  librar- 
ies, which  can  be  linked  into  applications  which  use  them.  The  applications  distributed 
with  the  Toolkit  include  the  various  translators  described  in  [Clark90a].  These  are: 
Fed-X-QDES,  the  Express-to-Smalltalk-80™  translator;  Fed-X-SQL  [Morris90],  the 
Express-to-SQL  translator,  STEPparse-SQL,  the  STEP  physical  file-to-Smalltalk-80 
translator;  and  STEPwf-SQL  [Nickerson90],  the  STEP-to-SQL  database  loader. 

In  addition  to  the  various  design  and  usage  documents  referenced  elsewhere,  technical 
reference  manuals  on  the  Express  [Clark90d]  and  STEP  [Clark90e]  Working  Forms  are 
also  available,  as  is  an  administrative  guide  for  QDES  [Clark90g]. 

The  Toolkit  distribution  may  be  installed  anywhere  on  a particular  filesystem.  For  sim- 
plicity, the  root  directory  of  the  distribution  is  referred  to  as  ~pdes/  throughout  the 
technical  documentation.  This  root  directory  contains  a number  of  subdirectories  of  in- 
terest, which  we  now  describe.  Brief  descriptions  also  appear  in  -pdes /README. 

The  directories  ~pdes/bin/,  ~pdes/ include/,  and  ~pdes/ lib/  contain,  re- 
spectively, Toolkit  application  binaries,  C header  ( . h)  files  for  the  Toolkit  libary  mod- 
ules, and  the  Toolkit  object  libraries  ( . a files)  themselves.  PostScript®  and/or  ASCII 
versions  of  the  Toolkit  documentation  can  be  found  in  ~pde  s / do  c s / . V arious  utility 
tools  which  are  needed  to  build  or  run  pieces  of  the  Toolkit  are  in  ~pdes/ etc/. 
QDES,  the  STEP  model  editor,  being  written  in  Smalltalk-80,  does  not  quite  fit  into  a 
C-oriented  directory  layout,  and  so  is  in  ~pdes/ applications/ qdes/.  Finally, 
the  directory  ~pdes/src/  contains  the  source  code  for  the  Toolkit  libraries  and  the 


1.  The  Free  Software  Foundation  (FSF)  of  Cambridge,  Massachusetts  is  responsible  for  the  GNU  Project, 
whose  ultimate  goal  is  to  provide  a free  implementation  of  the  Unix  operating  system  and  environment. 
These  tools  are  not  in  the  Public  Domain;  rather,  FSF  retains  ownership  d copyright  pnviledges,  but  grants 
free  distribution  nghts  under  certain  terms.  At  this  writing,  further  infor  ion  is  available  via  electronic  mail 
on  the  Internet  from  gnu@prep.ai.mit.edu 

2.  Vem  Paxson’s  Fast  Lex  is  usually  distributed  with  GNU  software,  although,  being  in  the  Public  Domain, 
it  is  not  an  FSF  product  and  does  not  come  under  the  FSF  licensing  restrictions. 
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2.1 


Working  Form-based  applications  distributed  with  the  Toolkit.  There  is  a separate  sub- 
directory for  each  library  and  for  each  application.  This  src/  directory  also  includes 
a subdirectory  called  Template/,  which  includes  a Makefile  template  which  can 
be  used  as  a model  when  building  new  applications  which  use  the  Toolkit. 


Conventions 

Each  Working  Form  is  composed  of  a number  of  data  abstractions.  Each  of  these  ab- 
stractions is  implemented  as  a separate  module.  Modules  share  only  their  interface 
specifications  with  other  modules.  For  example,  consider  a module  called  Foo,  com- 
posed of  two  C source  files,  f oo  . c and  foo  . h.  The  former  contains  the  body  of  the 
module,  including  all  non-inlined  functions.  The  latter  contains  function  prototypes  for 
the  module,  as  well  as  all  type  and  macro  definitions.  In  addition,  global  variables  are 
defined  in  f oo  . h.  These  declarations  are  made  using  two  special  macros: 


#ifdef  FOO_C 

# define  GLOBAL 

# define  INITIALLY (value)  = value 
#else 

# define  GLOBAL  extern 

# define  INITIALLY (value) 

#endi f FOO_C 

GLOBAL  int  FOO_GLOBAL_INT  INITIALLY ( 4 ) ; 

This  allows  the  same  declarations  to  be  used  both  in  f oo  . c and  in  other  modules 
which  use  it:  when  f oo  . h is  included  in  foo  . c,  FOO_GLOBAL  has  storage  declared 
and  is  initialized.  When  f oo  . h is  included  elsewhere,  an  uninitialized  extern  dec- 
laration is  produced.  Finally,  f oo  . h contains  inline  function  definitions.  If  the  C com- 
piler supports  inline  functions  (as  GCC  does),  these  are  declared  static  inline  in 
every  module  which  includes  foo  . h,  including  f oo  . c itself.  Otherwise,  they  are  un- 
defined except  when  included  in  foo  . c,  when  they  are  compiled  as  ordinary  func- 
tions. 


The  type  defined  by  module  Foo  is  named  Foo.  Access  functions  are  named  as 
FOO  function  ( ) ; this  function  prefix  is  abbreviated  for  longer  abstraction  names,  so 
that  access  functions  for  type  Foolhardy_Bartender  might  be  of  the  form 
FOO_BARf unction  ( ) . Some  functions  may  be  implemented  as  macros;  they  are 
not  distinguished  typographically  from  other  functions,  and  are  guaranteed  not  to  have 
unpleasant  side  effects  like  evaluating  arguments  more  than  once.  These  macros  are 
thus  virtually  indistinguishable  from  functions.  Functions  which  are  intended  for  inter- 
nal use  only  are  named  FOO_funct ion  ( ) , and  are  usually  static  as  well,  unless 
this  is  not  possible.  Global  variables  are  often  named  FOO_var  iable;  most  enumer- 
ation identifiers  and  constants  are  named  FOO_CONSTANT  . For  example,  every  ab- 
straction defines  a constant  FOO_NULL,  which  represents  an  empty  or  missing  value  of 
the  type. 
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There  are,  of  course,  exceptions  to  all  of  these  rules.  The  global  variable  and  enumer- 
ation identifier  rules  are  the  most  frequendy  broken.  Library  modules  which  were  de- 
veloped before  all  of  the  rules  solidified,  as  well  as  components  which  were  not 
developed  locally  by  the  Toolkit  project,  tend  to  stretch  the  rules  more  than  the  actual 
Working  Form  modules,  which  have  tended  to  be  more  dynamic  later  in  the  project. 

2.2  Object-Oriented  Framework  Modules:  Class  and  Object 

Most  of  the  Working  Form  abstractions  are  implemented  on  top  of  the  Class  and  Object 
modules  defined  in  libmisc.  Together,  these  modules  provide  a simple  object-ori- 
ented framework  on  which  various  abstractions  can  be  built.  The  Class  module  manip- 
ulates representations  of  classes  in  the  object-oriented  sense,  defining  management 
operations  for  classes  of  values  and  representing  sub-  and  supertype  relationships  be- 
tween these  classes.  The  Object  module  supports  instantiation  of  these  classes.  It  ac- 
tually performs  the  management  operations  specified  bv  an  Object’s  class,  and 
interprets  the  class  hierarchy  defined  by  a set  of  sub-  ai.  . supertype  relationships  be- 
tween classes. 

2.3  A Note  on  Memory  Management  and  Garbage  Collection 

In  reading  various  portions  of  the  Toolkit  technical  documentation,  one  may  get  the  im- 
pression that  some  reasonably  intelligent  memory  management  is  done.  This  is  not  en- 
tirely true.  The  NIST  PDES  Toolkit  is  primarily  a research  tool.  This  is  especially  true 
of  the  Express  and  STEP  Working  Forms.  The  Working  forms  allocate  huge  chunks  of 
memory  without  batting  an  eye,  and  this  memory  often  is  not  released  until  an  applica- 
tion exits.  Hooks  for  doing  memory  management  do  exist  (e.g.,  OBJf  ree  ( ) and  ref- 
erence counts),  and  some  attempt  is  made  to  observe  them,  but  this  is  not  given  high 
priority  in  the  current  implementation. 

3 Compiling  With  the  Toolkit:  The  Makefile 
Template 

The  file  -pdes/src/Template/Makef ile  (reproduced  in  Appendix  B)  in  the 
Toolkit  distribution  is  a skeletal  Makefile  which  can  be  configured  to  build  a wide 
variety  of  applications  which  use  one  or  both  of  the  Working  Forms.  This  Makefile 
uses  a number  of  macros  and  rules  which  are  defined  in 

~pdes / include/make_rules.  It  assumes  that  the  source  code  for  the  applica- 
tion to  be  built  resides  in  ~pdes/src/<appl>/. 

The  following  sections  discuss  the  various  classes  of  applications  which  can  be  built, 
and  the  appropriate  configuration  for  the  Makefile.  There  are  several  macros  de- 
fined in  the  Makefile  which  are  used  to  configure  an  application.  The  most  impor- 
tant, in  that  it  determines  how  the  application  will  use  the  Working  Form(s),  is  called 
LIBS.  This  macro  is  defined  in  the  section  of  the  Makefile  entitled  "Library  Selec- 
tion," which  contains  a number  of  possible  definitions.  Each  option  is  preceded  by  a 
comment  describing  the  situation  in  which  it  is  appropriate;  exactly  one  definition 
should  be  uncommented.  Next,  two  options  are  given  for  the  CFLAGS  macro:  one  for 
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STEP  applications  and  one  for  applications  which  use  only  Express.  This  is  not  a nec- 
essary distinction,  since  things  will  always  build  correctly  with  the  former  definition;  it 
is  provided  for  the  benefit  of  those  who  (like  the  author)  prefer  possibly  inordinate  neat- 
ness. 

There  are  two  macros  which  can  be  used  to  specify  the  auxiliary  object  ( . o)  files  and 
libraries  ( . a files)  required  by  the  application.  Object  files  should  be  named  in  the 
OFILES  macro;  several  sample  definitions  are  included  for  the  applications  provided 
with  the  toolkit.  The  macro  MYLIBS  can  contain  any  additional  libraries  which  are  re- 
quired by  the  application. 

In  addition  to  the  fundamental  configuration  options  discussed  above,  there  are  several 
more  macros  which  can  be  used  to  make  "cosmetic"  changes  to  an  application.  At  the 
top  of  the  Makefile  is  a macro  called  CC,  which  selects  the  C compiler  to  be  used. 
Common  options  are  /bin/cc  (the  vendor-supplied  compiler  under  Unix)  and 
$ (GCC)  , which  should  point  to  the  Gnu  Project’s  C Compiler.  The  contents  of 
MY_CFLAGS  are  passed  to  every  invocation  of  $ (CC)  ; this  is  the  place  to  add  debug- 
ging and/or  optimization  flags,  for  example.  The  default  rule  for  compiling  . c files 
(from  ~pdes / include/make_ruies)  probably  should  not  be  changed,  but  it  ap- 
pears in  the  template  to  provide  a hook  for  unforeseen  requirements.  Finally,  toward 
the  end  of  the  Make  f i le  is  a macro  called  PROG.  This  macro  holds  the  name  of  the 
executable  which  will  be  built. 

The  Makefile  provides  three  targets:  $ (PROG)  rebuilds  the  application  from 
scratch,  as  necessary.  The  relink  target  assumes  that  all  . o files  and  libraries  are  up- 
to-date,  and  simply  relinks  the  application.  This  is  useful,  for  example,  when  one  of  the 
Toolkit  libraries  has  been  rebuilt,  but  the  application  source  itself  has  not  been  changed. 
The  last  target,  clean,  removes  $ (PROG)  and  $ (OFILES ) . This  rule  may  be  mod- 
ified for  a particular  application.  Any  additional  rules  which  are  required  to  build  the 
application  can  be  added  at  the  end  of  the  Makefile. 

3.1  STEPparse  STEP  Translators 

The  first  class  of  applications  which  we  examine  are  the  STEP  translators.  These  pro- 
grams parse  a STEP  Physical  File  into  the  STEP  Working  Form  and  then  invoke  one  or 
more  report  generators  which  traverse  these  data  structures  and  produce  output  files 
containing  some  or  all  of  the  product  model  represented  in  a different  format.  Although 
the  STEPwf-SQL  database  loader  is  usually  included  in  this  category,  it  is  not,  strictly 
speaking,  a translator:  Rather  than  producing  an  output  file  or  files  containing  an  SQL 
representation  of  the  data  to  be  loaded,  STEPwf-SQL  actually  directly  loads  the  data- 
base by  making  calls  to  SQL-compliant  library  routines. 

The  Make  macro  $ (STEP_LIBS)  expands  to  list  all  of  the  libraries  needed  to  create 
a STEP  translator.  These  include:  libstep  . a and  libexpress  . a,  the  STEP  and 
Express  Working  Form  libraries;  libmisc  . a and  libbison  . a;  and  -11,  which 
provides  support  for  lexical  analyzers  produced  by  Lex.  The  first  four  are  located  in 
~pdes/ lib/,  while  libl . a is  normally  found  in/usr/lib/.  The  order  in  which 
these  libraries  are  listed  is  significant:  libstep  and  libexpress  both  include  def- 
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initions  of  main  ( ) , the  standard  entry  point  to  a C program.  To  build  a STEP  transla- 
tor, the  first  definition  of  main  ( ) which  the  linker  finds  must  be  the  STEPparse  driver, 
which  is  in  libstep  . a. 

In  addition  to  these  libraries,  two  more  pieces  of  code  are  needed  to  build  a complete 
translator:  a report  generator  and  a linkage  mechanism  for  this  report  generator.  The 
latter  is  needed  because  the  translator  can  load  its  report  generator(s)  in  either  of  two 
ways:  it  can  load  a specific  one  at  compile  time,  or  it  can  dynamically  load  one  or  more 
at  run  time.  The  dynamic  approach  has  at  least  two  major  advantages:  It  allows  multi- 
ple output  formats  to  be  produced  by  a single  executable;  and  it  allows  several  reports 
to  be  created  by  a single  run  of  the  translator,  so  that  the  parsing  phase  need  only  be 
executed  once.  This  approach  has  the  unfortunate  disadvantage  that  it  is  (currently) 
only  available  under  BSD  4.2  Unix  and  its  derivates;  it  is  therefore  considered  optional 
in  the  current  incarnation  of  the  Toolkit. 

In  the  library  selection  section  of  the  Makefile,  the  first  two  options  are  alternate  def- 
initions of  LIBS  for  building  a STEP  translator.  The  first  is  for  a translator  with  a sin- 
gle, statically  bound  report  generator.  Since  the  static  linkage  facility  is  included  in 
libstep  . a,  the  linkage  mechanism  is  not  explicitly  listed.  The  second  alternative, 
for  a translator  with  dynamically  bound  report  generators,  selects 
~pdes/lib/step_dynamic  . o to  provide  the  run-time  linking  mechanism.  In  ad- 
dition, it  adds  libdyna  . a to  the  link. 

If  a dynamically  loading  translator  is  being  built,  then  no  report  generator  object  file 
should  be  listed  in  the  OFILES  macro,  since  the  report  generator  will  be  selected  at  run 
time.  The  first  sample  definition  of  OFILES  is  appropriate  here.  If  a report  generator 
is  being  loaded  at  build  time,  then  any  object  files  which  are  needed  to  implement  it 
should  be  listed  in  this  macro.  The  second  option  for  OFILES  lists  the  QDES/Small- 
talk  report  generator,  and  is  used  to  build  the  STEPparse-QDES  translator. 

3.2  Fed-X  Express  Translators 

The  process  of  configuring  the  Makefile  to  build  an  Express  translator  is  similar  to 
that  described  for  STEP  translators.  The  $ (EXP_LIBS)  macro  expands  to  the  list  of 
libraries  needed  to  build  a Fed-X  translator;  these  include  the  same  libraries  listed  in 
$ ( STEP_LIBS ) , with  the  exception  of  libstep  . a.  Again,  there  are  two  possible 
definitions  of  LIBS.  The  first  selects  a build-time  (static)  linkage  (which  is  included 
in  libexpress  . a);  the  second  adds  ~pdes / 1 ib/express_dynamic  . o and  - 
ldyna  for  run-time  (dynamic)  linkage. 

As  in  the  case  of  a STEP  translator,  a dynamically  bound  Express  translator  requires  no 
object  files  in  $ (OFILES) , while  a statically  bound  translator  expects  to  find  the  re- 
port generator  in  this  macro.  The  first  sample  definition  of  OFILES  can  again  be  used 
in  the  former  case,  while  the  third  is  used  to  build  the  Fed-X-QDES  translator. 
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3.3  Other  Applications 

We  now  turn  to  the  more  free-form  applications  which  might  make  use  of  the  Express 
and/or  STEP  working  forms.  A notable  difference  between  these  applications  and  the 
translators  is  that  the  programmer  must  define  the  flow  of  control,  by  providing 
main  () . As  mentioned  above,  both  the  STEP  library  and  the  Express  library  include 
definitions  of  main  ( ) which  are  used  to  drive  the  respective  translators;  source  code 
for  these  can  be  found  in  ~pdes/src/ step/ step  . c and 

~pdes/src/express/  fedex  . c,  respectively.  These  might  serve  as  useful  start- 
ing points  for  other  applications.  In  general,  the  first  two  passes  of  the  Express  parser 
(EXPRESSpass_l  ( ) and  EXPRESSpass_2  ( ) ) will  have  to  be  run  in  any  applica- 
tion, unless  a conceptual  schema  is  to  be  built  by  hand.  EXPRESSpass_3  ( ) invokes 
a report  generator  via  the  selected  linkage  mechanism.  The  call  which  invokes  the 
STEP  parser  is  STEPparse  ( ) ; this  is  the  simplest  way  of  building  an  instantiated 
STEP  model.  A STEP  report  generator  is  invoked  by  calling  S TEP  r epo  r t ( ) ; unfor- 
tunately, Express  and  STEP  report  generators  and  associated  linkages  currently  cannot 
coexist  in  a single  executable.  This  restriction  is  not  due  to  anything  fundamental,  and 
so  may  disappear  should  there  be  sufficient  demand. 

Assume  for  the  moment  the  no  STEP  or  Express  report  generators  are  needed.  In  this 
case,  it  is  quite  simple  to  configure  the  Makefile  to  use  one  or  both  of  the  Working 
Form(s):  First,  set  LIBS  to  either  $ (STEP_LIBS)  or  $ (EXP_LIBS) , depending  on 
which  Working  Form  is  needed  (remember  that  the  former  includes  the  latter,  so  that  it 
is  never  necessary  to  use  both  macros  at  once).  These  are  the  last  two  sample  defini- 
tions in  the  library  selection  section.  Next,  in  OFILES  and  MY_LIBS  list  the  object 
files  and  libraries  which  the  application  uses.  Bear  in  mind  that  the  application’s 
main  ( ) must  appear  in  $ ( OF  I LE S ) in  order  to  override  the  default  one  which  will 
otherwise  be  found  in  one  of  the  Working  Form  libraries.  Finally,  be  sure  to  set  PROG 
to  the  name  of  the  application  which  will  be  built. 

We  now  return  to  the  problem  of  an  application  which  will  use  a STEP  or  Express  re- 
port generator  without  being  just  a translator.  A main  ( ) must  be  provided  for  this  ap- 
plication and  included  in  the  OFILES  macro,  just  as  in  the  previous  case.  What  gets 
messy  is  the  library  selection.  To  use  a Fed-X  report  generator  in  an  application  which 
uses  only  the  Express  working  form,  or  to  use  a STEPparse  report  generator  in  a STEP 
application,  just  select  the  appropriate  LIBS  macro  for  a translator  with  the  same  report 
generator  linkage,  one  of  the  first  four  sample  definitions.  To  build  an  application 
which  produces  Fed-X  reports  while  using  the  STEP  working  form,  choose  either  the 
static  or  the  dynamic  binding  option  from  the  section  "STEP  applications  with  Express 
report  generators"  in  the  Makefile  template.  This  will  select  the  full  set  of  STEP  li- 
braries, and  pull  in  the  specified  Fed-X  output  linkage. 

4 Basic  Libraries 

This  section  discusses  the  three  basic  libraries  in  the  Toolkit.  Portions  of  the  libraries 
are  discussed  in  varying  levels  of  detail,  according  to  the  level  of  code  reuse  from  other 
sources  (who  may  or  may  not  provide  additional  documentation). 
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4.1  The  Library  of  Miscellany:  libmisc.a 

This  library  contains  various  modules  which  are  used  throughout  the  Toolkit.  The  ab- 
stractions in  most  common  use  are  String,  Linked_List,  Dictionary,  and  Error.  Other 
modules  in  this  library  are  Stack,  Dynamic,  and  Hash.  The  object  library  is 
~pdes/lib/libmisc  . a,  and  the  sources  can  be  found  in 
~pdes/src/libmisc/  (.h  files  in  ~pdes/include/). 

The  file  ~pdes/  include /basic  . h includes  various  simple  definitions:  a 
typedef  Boolean,  as  an  enumeration  of  { false,  true  };  a Generic  pointer 
type;  MAX  and  MIN  macros,  etc.  It  is  included  by  every  source  file  in  the  Toolkit. 

4.1.1  Class 

A Class  encapsulates  meta-data  about  a class  of  similar  data  objects.  It  includes  various 
generic  manipulation  functions  and  information  about  how  instances  of  the  class  are  ar- 
ranged in  memory. 


Type:  Constructor 

Definition:  void  (*)(Genenc) 

Description:  The  constructor  function  for  a class  initializes  the  block  of  class-specific  data  for  an 

instance  of  the  class.  It  does  not  allocate  storage  for  the  block  itself. 


Type:  Copier 

Definition:  void  (*)(Generic,  Genenc) 

Description:  The  copier  function  for  a class  copies  a block  of  class-specific  data  for  an  instance  of 

the  class  into  a second  such  block. 


Type:  Comparator 

Definition:  Boolean  (*)(Generic,  Generic) 

Description:  The  comparator  function  for  a class  compares  the  blocks  of  class-specific  data  from 

two  instances  of  the  class;  it  returns  false  if  the  blocks  are  considered  unequal  and  true 
otherwise. 


Type:  Destructor 

Definition:  void  (*)(Generic) 

Description:  The  destructor  function  for  a class  releases  the  various  class-specific  components  of  an 

instance  of  the  class.  It  does  not  release  the  data  block  itself. 


Procedure: 

Parameters: 


Returns: 

Description: 

Errors: 


CLASScreate 

Suing  name  - name  of  new  class 

Class  super  - parent  of  new  class 

Constructor  create  - constructor  for  instance  data 

Copier  copy  - copy  method  for  instance  data 

Comparator  compare  - comparison  method  for  instance  data 

Destructor  delete  - destructor  for  instance  data 

Error  *errc  - buffer  for  error  code 

Class  - the  newly  created  class 

Creates  and  returns  a new  class. 

— none  -- 
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Procedure: 

Parameters: 

Returns: 

Description: 

Errors: 

CLASScreate_dataless 

String  name  - name  of  new  class 

Class  super  - parent  of  new  class 

Error  *errc  - buffer  for  error  code 

Class  - the  newly  created  class 

Creates  and  returns  a new  dataless  class.  A dataless  class  has  no  instance  data  slot  of 
its  own,  and  so  does  not  require  a constructor,  destructor,  copier,  or  comparator. 

— none  -- 

Procedure: 

Parameters: 

Returns: 

Description: 

CLASS  get_comparator 

Class  class  - class  to  examine 

Comparator  - the  comparator  for  the  class 

Retrieves  a class’  instance  data  comparison  method. 

Procedure: 

Parameters: 

Returns: 

Description: 

CLASSget_constructor 

Class  class  - class  to  examine 

Constructor  - the  constructor  for  the  class 

Retrieves  a class’  instance  data  constructor. 

Procedure: 

Parameters: 

Returns: 

Description: 

CLASSget_copier 

Class  class  - class  to  examine 

Copier  - the  copier  for  the  class 

Retrieves  a class’  instance  data  copy  method. 

Procedure: 

Parameters: 

Returns: 

Description: 

CLASSget_destructor 

Class  class  - class  to  examine 

Destructor  - the  destructor  for  the  class 

Retrieves  a class’  instance  data  destructor. 

Procedure: 

Parameters: 

Returns: 

CLASS  get_name 

Class  class  - class  to  examine 

String  - the  name  of  the  class 

Procedure: 

Parameters: 

Returns: 

Description: 

CLASSget_size 

Class  class  - class  to  examine 
int  - size  of  class’  instance  data  slot 

Retrieves  the  size  (in  bytes)  of  a class’  instance  data. 

Procedure: 

Parameters: 

Returns: 

Description: 

CLASSget_slot 

Class  class  - class  to  examine 
int  - slot  number  of  class 

Retrieves  the  slot  number  in  which  a class’  instance  data  is  stored.  Note  that  this  is  a 
constant  for  a given  class. 

Procedure: 

Parameters: 

Returns: 

CLASSget_superclass 

Class  class  - class  to  examine 

Class  - the  class’  immediate  superclass 
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Procedure: 

Parameters: 

CLASS  inhen  ts_from 

Class  child  - the  class  whose  ancestry  is  to  be  tested 

Class  parent  - the  hypothetical  parent  class  to  search  for 

Returns: 

Description: 

Boolean  - Is  the  parent  class  in  the  child’s  superclass  chain? 

Determine  whether  a class  (the  child)  is  a descendant  of  a particular  class  (the  parent). 
This  function  reports  true  in  the  degenerate  case  where  parent  ==  child. 

4.1.2  Dictionary 

A Dictionary  consists  of  a naming  function  and  a homogeneous  collection.  The  collec- 
tion is  ordered  alphabetically  according  to  the  items’  names,  as  reported  by  the  naming 
function.  The  current  implementation  of  this  module  makes  no  claim  to  efficiency:  it 
is  simply  a wrapper  around  the  Linked  List  module.  Entries  are  added  by  insertion  sort, 
and  retrieval  is  by  linear  search. 


Type: 

Naming_Function 

Definition: 

Description: 

String  (*)(Generic) 

This  is  the  type  of  the  function  which  a Dictionary  expects  to  use  to  retrieve  the  name 
of  one  of  its  entries. 

Procedure: 

Parameters: 

DICTadd_entry 

Dictionary  dictionary  - dictionary  to  modify 

Generic  entry  - entry  to  be  added 

Error*  errc  - buffer  for  error  code 

Returns: 

Requires: 

Description: 

Generic  - the  added  entry,  or  null  on  failure 

Entry  is  of  an  appropriate  type  for  the  dictionary’s  naming  function. 

Adds  an  entry  to  a dictionary,  provided  that  the  dictionary  does  not  yet  contain  a 
definition  for  the  entry’s  name  (as  given  by  the  dictionary’s  naming  function). 

Errors: 

ERROR  duplicate  entry  - An  entry  with  the  given  name  already  appears  in  the 
dictionary 

Procedure: 

Parameters: 

DICTcreate 

Naming_Function  func  - the  naming  function  to  be  used  by  the  new  dictionary 

Error*  errc  - buffer  for  error  code 

Returns: 

Description: 

Dictionary  - the  newly  created  dictionary 

Creates  an  empty  dictionary.  Entries  will  be  sorted  according  to  the  strings  they 
produce  when  passed  to  the  naming  function  given  in  this  call.  Thus,  iteml  will 
precede  item2  exactly  when  st rcmp  (func  (iteml)  , func(item2))  < 0. 

Errors: 

— none  - 

Procedure: 

Parameters: 

Returns: 

Description: 

DICTinitialize 

- none  - 

void 

Initialize  the  Dictionary  module. 

Procedure: 

Parameters: 

DICTlookup 

Dictionary  dictionary  - the  dictionary  to  look  in 

String  name  - the  name  to  look  for 

Returns: 

Description: 

Generic  - the  entry  whose  name  matches  that  given 

Looks  up  a name  in  a dictionary.  If  no  matching  entry  can  be  found,  NULL  is  returned. 
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Procedure: 

Parameters: 

Returns: 

Description: 


DICTremove_entry 

Dictionary  dictionary  - the  dictionary'  to  modify 
String  name  - the  name  of  the  entry  to  remove 
Generic  - the  entry  removed 

Removes  the  named  entry  from  a dictionary,  and  returns  this  entry  to  the  caller.  If  no 
entry  with  the  given  name  can  be  found,  NULL  is  returned. 


4.1.3 


Dynamic 

This  module  puts  a clean  wrapper  on  the  routines  in  libdyna  . a (see  section  4.3). 
Only  two  calls  are  provided. 


Procedure: 

Parameters: 

Returns: 

Description: 


DYNAinit 
— none  - 
void 

Initializes  the  dynamic  loading  module.  This  must  be  called  with  a rgv  in  scope,  as  it 
is  actually  a macro  which  examines  argv  [ 0 ] . Alternatively,  call 
DYNA_init  (String  me ),  whose  single  parameter  should  be  argv  [ 0 ] . This 
method  is  not  recommended,  but  will  work  in  situations  where,  for  some  reason,  the 
value  of  argv  [ 0 ] is  available  while  argv  itself  is  not. 


Procedure: 

Parameters: 

Returns: 

Description: 


DYNAload 

String  filename  - the  name  of  the  object  file  to  load 
void  (*)()  - the  loaded  file’s  entry  point 

Loads  the  named  object  file  into  the  currently  running  image,  and  performs  symbol 
relocation  as  necessary.  The  entry  point  to  the  file  is  returned  as  a pointer  to  a funcuon 
of  no  arguments  which  returns  vo  id.  If  an  error  occurs  during  the  loading  process,  it 
is  reported  to  stderr  and  NULL  is  returned  as  the  entry  point. 


4.1.4  Error 

Error  repotting  throughout  the  Toolkit  is  managed  by  the  Error  abstraction.  This  mod- 
ule was  not  present  in  the  initial  Toolkit  design;  rather,  it  has  grown  in  response  to  needs 
which  have  appeared  over  the  course  of  the  Toolkit’s  development.  Some  of  the  spec- 
ifications and  behavior  thus  seem  contrived.  The  Error  module  allows  subordinate  rou- 
tines to  report  error  conditions  to  their  callers,  and  allows  the  callers  to  strongly 
influence  the  form  of  the  message  reported  to  the  user.  In  order  to  do  this,  the  caller  is 
trusted  to  test  for  and  report  error  conditions.  A caller  who  breaches  this  trust  is  asking 
for  trouble,  since  it  is  the  act  of  actually  repotting  the  error  which  gives  control  of  the 
program  to  the  Error  module,  allowing  it  to  take  appropriate  steps  (such  as  halting  the 
program  on  a fatal  error). 

Modules  which  may  wish  to  report  error  conditions  create  instances  of  type  Error  at 
initialization  time.  Routines  which  may  report  errors  then  expect  a pointer  to  an  error 
buffer  as  a parameter,  declared  by  convention  as  the  last  parameter,  Error*  errc. 
On  exit,  this  buffer  will  contain  either  ERROR_none,  indicating  successful  comple- 
tion, or  some  error  code.  The  caller  may  then  report  the  error,  filling  in  the  necessary 
blanks  in  the  format  specification  (see  below),  attempt  to  recover,  or  simply  ignore  it 
(realizing  that  ignoring  any  but  the  most  innocuous  errors  will  most  likely  lead  to  trou- 
ble later  on). 
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An  Error  has  two  main  components.  The  severity  of  an  error  indicates  how  serious  the 
error  is.  A warning  may  be  reported  to  the  user,  but  is  not  really  considered  an  error. 
Continuing  past  a warning,  or  even  100  warnings,  should  cause  no  serious  problems. 
An  error,  on  the  other  hand,  must  be  noted  by  the  program:  The  program  need  not  halt 
immediately,  but  at  some  point  in  the  future,  it  will  become  impossible  to  proceed.  An 
error  of  "exit"  severity  causes  the  program  to  exit  immediately,  as  gracefully  as  possi- 
ble. An  error  of  "dump”  severity  causes  the  program  to  dump  core  and  exit  immediate- 
ly. All  of  these  actions  are  taken  only  when  the  error  is  reported  (with 
ERRORreport  ( ) ),  rather  than  when  the  error  is  discovered. 

The  other  component  of  an  error  is  its  text.  This  is  a pr  int  f-style  format  string, 
whose  arguments  will  be  filled  in  when  the  error  is  reported.  For  example,  the  text  for 
ERROR_memory_exhausted  is  "Out  of  memory  allocating  %d  for  %s."  When  this 
error  is  reported,  the  amount  of  memory  requested  and  its  intended  purpose  should  be 
provided  by  the  programmer: 

ERRORreport (ERROR_memory_exhausted, 

block_size,  "file  buffer  block"); 

For  specifications  of  the  Errors  defined  in  libmisc  . a,  see  section  4.1.8. 

For  greater  flexibility  in  error  reporting.  Errors  can  be  enabled  and  disabled  individual- 
ly. Disabled  errors  which  are  given  to  ERRORreport  ( ) will  be  ignored,  just  as  ER- 

ROR_none  is. 

An  alternate  routine  for  reporting  errors  is  ERRORreport_with_l  ine  ()  , which 
inserts  a line  number  indication  at  the  beginning  of  a message.  Particularly  when  line 
numbers  are  included,  it  may  be  useful  to  sort  error  messages  before  printing  them. 
This  can  be  done  by  asking  that  error  messages  be  buffered.  When  this  message  buffer 
is  flushed,  its  contents  are  sorted  according  to  the  third  column,  which  is  where  ER- 
RGRreport  with_line()  puts  the  line  number.  This  feature  is  used  in  the  second 
pass  of  Fed-X,  for  example,  where  the  Express  Working  Form  data  structures  are 
walked  in  the  most  convenient  order,  which  bears  little  resemblance  to  the  order  in 
which  the  original  constructs  appeared  in  the  source  file.  Any  error  messages  encoun- 
tered are  buffered,  and  all  are  sorted  and  flushed  after  the  entire  pass  is  complete,  re- 
sulting in  sensibly  ordered  output. 


Type:  Severity 

Description:  This  type  is  an  enumeration  of  SEVERITY_WARNING,  SEVERlTY_ERROR, 

SEVERITY  EXIT,  SEVERITY_DUMP,  and  SEVERITY_MAX  (which  is  guaranteed 
to  be  the  higTest  possible  severity  of  any  error). 


Procedure: 

Parameters: 

Returns: 

Description: 


ERRORbuffer_messages 

Boolean  flag  - to  buffer  or  not  to  buffer 

void 

Selects  buffering  of  error  messages.  Buffering  is  useful  when  error  messages  are 
produced  by  ERRORreport_with_line  ( ) , as  it  allows  the  messages  to  be  sorted 
according  to  line  number  before  being  displayed. 
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Procedure: 

Parameters: 

Returns: 

Description: 

ERRORclear_occurred_flag 
— none  - 

void 

Clear  the  flag  which  is  used  to  remember  whether  any  errors  have  occurred. 

Procedure: 

Parameters: 

ERRORcreate 

String  message  - message  to  print  for  error 

Seventy  seventy  - seventy  of  error 

Error*  errc  - buffer  for  error  message 

Returns: 

Description: 

void 

Create  a new  error.  The  meanings  of  the  various  seventy  levels  are  as  follows: 
SEVERITY  WARNING  indicates  that  a warning  message  should  be  generated.  This 
will  not  interfere  with  later  operation  of  the  program,  severity  ERROR  produces 
an  error  message,  and  the  fact  that  an  error  has  occurred  will  be  remembered  (e.g.,  so 
that  no  reports  will  be  generated).  SEVERITY_EXIT  indicates  that  the  error  is  fatal, 
and  should  cause  the  program  to  exit  immediately.  SEVERITY  DUMP  causes  the 
program  to  exit  immediately  and  produce  a core  dump.  SEVERITY  MAX  is 
guaranteed  to  be  the  highest  seventy  level  available.  The  message  string  may  contain 
print f -style  formatting  codes,  which  will  be  filled  when  the  message  is  pnnted. 

Procedure: 

Parameters: 

Returns: 

Description: 

ERRORdisable 

Error  error  - the  error  to  disable 
void 

Disable  an  error,  so  that  the  ERRORreport  calls  will  ignore  it. 

Procedure: 

Parameters: 

Returns: 

Description: 

ERRORenable 

Error  error  - the  error  to  enable 
void 

Enable  an  error,  ensunng  that  the  ERRORreport  calls  will  report  it. 

Procedure: 

Parameters: 

Returns: 

Description: 

ERRORflush_messages 
— none  -- 

void 

Flushes  the  error  message  buffer  to  the  standard  output,  sorted  by  line  number  (the 
third  column). 

Procedure: 

Parameters: 

Returns: 

Description: 

ERRORhas_error_occ  urred 
— none  -- 

Boolean  - has  an  error  occurred? 

Check  whether  any  errors  (severity  >=  SEVERITY  ERROR)  have  occurred 
since  the  flag  was  last  cleared. 

Procedure: 

Parameters: 

Returns: 

Description: 

ERRORinitialize 

— none  -- 

void 

Initialize  the  Error  module.  If  not  explicitly  called,  this  is  nonetheless  called  when 
necessary.  Thus,  it  can  safely  be  ignored,  but  is  included  for  completeness. 

Procedure: 

Parameters: 

Returns: 

ERRORis_enabled 

Error  error  - the  error  to  test 

Boolean  - is  reporting  of  this  error  enabled? 
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Procedure: 

ERRORreport 

Parameters: 

Error  what  - the  error  to  report 
...  - arguments  for  error  string 

Returns: 

Description: 

void 

Report  an  error,  taking  action  appropriate  for  its  seventy.  The  remaining  arguments 
should  match  the  format  codes  in  the  message  string  for  the  error. 

Procedure: 

Parameters: 

ERRORreport_withJine 

Error  what  - the  error  to  report 
int  line  - line  number  of  error 

Returns: 

Description: 

...  - arguments  for  error  string 
void 

Report  an  error,  including  a line  number.  Otherwise  identical  to  ERRORreport  ( ) . 

4.1.5  Hash 

The  Hash  module  emulates  Unix’s  hsearch  ( 3 ) package  with  dynamic  hashing.  The 
module  header  reads,  in  part: 

Dynamic  hashing,  after  CACM  April  1988  pp  446-457, 
by  Per-Ake  Larson. 

Coded  into  C,  with  minor  code  improvements,  and  with 
hsearch(3)  interface, 

by  e jp@ausmelb . oz , Jul  26,  1988:  13:16; 

The  code  was  downloaded  from  the  Internet,  and  is  used  in  the  Toolkit  with  only  cos- 
metic changes.  Note  that  this  is  an  incomplete  implementation  of  a hash  table  abstrac- 
tion: only  insertion  and  named  retrieval  are  supported. 


Type: 

Action 

Description: 

This  type  is  an  enumeration  of  HASH  FIND,  HASH  INSERT. 

Type: 

Description: 

Element 

The  entries  in  a hash  table  are  stored  as  Elements.  An  Element  has  a char*  (string) 
key,  a char*  data  field,  and  a next  pointer. 

Procedure: 
Paramet  -s: 

Returns. 

Description: 

HAS  He  reate 

unsigned  count  - estimated  maximum  number  of  table  elements 

Hash_Table  - the  new  hash  table 

Creates  a new,  empty  hash  table. 

Procedure: 

Parameters: 

Returns: 

Description: 

HASHdestroy 

Hash_Table  table  - the  table  to  be  destroyed 
void 

Destroys  a hash  table,  releasing  all  associated  storage. 
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Procedure: 

HASHsearch 

Parameters: 

Hash_Table  table  - the  table  to  search 

Element  item  - the  item  to  search  for/insert 

Action  action  - the  action  to  take  on  the  search  item 

Returns: 

Description: 

Element  - the  result  of  the  acuon 

If  the  table  already  contains  an  entry  whose  key  matches  that  of  the  item  given,  this 
entry  is  returned  unchanged.  Otherwise,  if  action  is  HASH_INSERT,  the  item  given 
is  inserted  into  the  hash  table  and  returned,  and  if  action  is  HASH_FTND,  NULL  is 
returned,  indicating  that  no  matching  entry  could  be  located. 

4.1.6  Linked  List 

The  Linked  List  abstraction  represent  heterogeneous  linked  lists.  Each  element  of  a list 
is  treated  as  an  object  of  type  Generic;  any  object  which  can  be  cast  to  this  type  can 
be  stored  in  a list.  Note  that  the  programmer  must  provide  himself  with  a mechanism 
for  determining  the  type  of  an  object  retrieved  from  a list:  this  module  maintains  no 
such  type  information. 


Type: 

Link 

Description: 

Each  element  of  a linked  list  is  stored  as  a Link,  which  has  next  and  prev  pointers 
and  a Generic  data  field. 

Procedure: 

Parameters: 

LISTadd_all 

Linked_List  list  - list  to  modify 

Linked_List  items  - list  of  items  to  add 

Returns: 

Description: 

void 

Add  the  contents  of  items  to  the  end  of  list. 

Procedure: 

Parameters: 

LISTadd_first 

Linked_List  list  - list  to  modify 

Generic  item  - item  to  add 

Returns: 

Description: 

Generic  - the  item  added 

Add  an  item  to  the  front  of  a list. 

Procedure: 

Parameters: 

LISTaddJast 

Linked_List  list  - list  to  modify 

Generic  item  - item  to  add 

Returns: 

Description: 

Generic  - the  item  added 

Add  an  item  to  the  end  of  a list. 

Iterator: 

Usage: 

LISTdo  ...  LISTod 

Linked_List  list; 

LISTdoOist,  <variable_name>,  <type>) 
process_value(<variable_name>); 

LISTod; 

Description: 

The  macro  pair  LISTdo  ( ) . . . LISTod;  are  used  to  iterate  over  a list  type  is  a C 
language  type;  variable  is  declared  to  be  of  this  type  within  the  block  bracketed  by 
these  two  macros,  variable  is  successively  assigned  each  value  on  the  list,  in  turn. 
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Procedure: 

Parameters: 

Returns: 

LISTempty 

Linked_List  list  - the  list  to  be  tested 

Boolean  - true  if  and  only  if  the  list  contains  no  elements 

Procedure: 

Parameters: 

Returns: 

Description: 

LISTinitialize 

— none  -- 

void 

Initialize  the  Lmked_List  module. 

Procedure: 

Parameters: 

Returns: 

Requires: 

LISTpeek_first 

Linked_List  list  - list  to  examine 

Generic  - the  first  item  on  the  list 
!LISTempty(List) 

Procedure: 

Parameters: 

Returns: 

Description: 

Requires: 

LISTremove_first 

Linked_List  list  - list  to  modify 

Generic  - the  item  removed 

Remove  the  first  item  from  a list  and  return  it. 
!LISTempty(list) 

4.1.7  Object 

Together  with  the  Class  module,  this  module  provides  an  object-oriented  framework  on 
which  class  hierarcies  with  data  inheritance  can  be  built.  One  aspect  of  the  Class/Ob- 
ject representation  deserves  comment.  An  Object  is  represented  as  a header  block  and 
a set  of  instance  data  slots.  Each  slot  contains  the  instance  data  specific  to  a particular 
class  in  the  ancestry  of  the  Object’s  class.  For  example,  if  Cartesian_Point  is  a 
subclass  of  Point,  and  Point  is  a subclass  of  Geometry,  which  has  no  superclass, 
then  an  instance  of  Cartesian_Point  will  contain  three  slots.  The  first  will  contain 
instance  data  for  a generic  Geometry  object;  the  next  will  contain  the  data  for  a 
Point  object;  and  the  last  will  contain  the  instance  data  which  is  specific  to  a 
Cartesian_Point.  The  instance  data  required  by  a particular  class,  then,  is  always 
found  in  the  same  slot:  In  the  example  above.  Geometry  data  will  always  be  found  in 
slot  0,  and  Cartes  ian_Point  data  in  slot  2.  This  slot  number  is  recorded  in  the  def- 
inition of  a Class.  A call  is  provided  to  retrieve  the  instance  data  from  a particular 
Class’  slot  in  an  Object  (see  OBJget_data  ( ) ). 


Procedure: 

Parameters: 


Returns: 

Requires: 

Description: 


Errors: 


OBJbecome 

Object  old  - object  to  replace  definition  of 
Object  new  - object  to  replace  with 
Error*  errc  - buffer  for  error  code 
void 

old  !=  OBJECT_NULL 
new  !=  OBJECT_NTJLL 

Replace  an  object  with  a new  object  All  references  to  the  old  object  will  refer  to  the 
new  object.  This  operation  is  not  commutative:  the  old  object  is  destroyed  in  the 
process. 

— none  -- 
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Procedure: 

Parameters: 

OBJcopy 

Object  object  - the  object  to  be  duplicated 

Error*  errc  - buffer  for  error  code 

Returns: 

Description: 

Object  - copy  of  object 

Creates  a duplicate  (deep  copy)  of  an  object.  The  contents  of  each  instance  data  slot 
are  copied  using  the  corresponding  class’  copy  method. 

Errors: 

— none  -- 

Procedure: 

Parameters: 

OBJcreate 

Class  class  - class  of  object  to  create 

Error*  errc  - buffer  for  error  code 

Returns: 

Description: 

Object  - the  newly  created  object 

Create  a new  object  of  a particular  class.  The  contents  of  each  instance  data  slot  are 
initialized  using  the  corresponding  class’  constructor. 

Errors: 

--  none  - 

Procedure: 

Parameters: 

OBJcreate_constant 

Class  class  - class  of  object  to  create 

Error*  errc  - buffer  for  error  code 

Returns: 

Description: 

Object  - the  newly  created  constant  object 

Create  a new  constant  object  of  a particular  class.  A constant  object  cannot  be 
modified.  The  contents  of  each  instance  data  slot  are  initialized  using  the 
corresponding  class’  constructor. 

Errors: 

--  none  -- 

Procedure: 

Parameters: 

OBJequal 

Object  objectl  - one  object  to  compare 

Object  object2  - one  object  to  compare 

Error*  errc  - buffer  for  error  code 

Returns: 

Description: 

Boolean  - are  the  objects  equal? 

Compares  two  objects  and  determines  whether  they  are  equal.  The  contents  of 
corresponding  instance  data  slots  are  compared  using  the  appropriate  class* 
comparison  method. 

Errors: 

— none  -- 

Procedure: 

Parameters: 

OBJfree 

Object  object  - the  object  to  be  freed 

Error*  errc  - buffer  for  error  code 

Returns: 

Description: 

void 

Releases  (a  reference  to)  an  object.  If  possible  (i.e.,  if  there  are  no  other  references  to 
this  object),  all  storage  associated  with  the  object  may  be  released.  The  contents  of 
each  instance  data  slot  are  freed  using  the  corresponding  class’  destructor. 

Errors: 

ERROR  manipulate  constant  - the  object  to  be  freed  is  a constant 

Procedure: 

Parameters: 

Returns: 

OBJget_class 

Object  object  - the  object  to  examine 

Class  - the  object’s  class 
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Procedure: 

Parameters: 


Returns: 

Description: 

Errors: 


OBJget_data 

Object  object  - the  object  to  examine 

Class  class  - the  class  for  which  instance  data  is  requested 

Error*  errc  - buffer  for  error  code 

Generic  - instance  data  for  object  from  the  appropriate  class 

Retrieves  a pointer  to  the  instance  data  for  an  object,  view'ing  the  object  as  an  instance 
of  a particular  class. 

--  none  — 


Procedure: 

Parameters: 

Returns: 

Description: 


OBJinitiaiize 
--  none  -- 
void 

Initialize  the  Object  module. 


Procedure: 

Parameters: 

Returns: 

Description: 


OBJis_constant 

Object  object  - the  object  to  test 
Boolean  - is  this  object  a constant? 
Determine  whether  an  object  is  a constant. 


Procedure: 

Parameters: 

Returns: 

Description: 


OBJis_kind_of 

Object  object  - the  object  to  examine 

Class  class  - the  class  to  test  for 

Boolean  - is  this  object  a member  of  the  class? 

Determines  whether  a particular  object  is  an  instance  of  a particular  class  or  of  any  of 
its  subclasses. 


Procedure: 

Parameters: 

Returns: 

Description: 


OBJreference 

Object  object  - the  object  to  be  referenced 

Object  - reference  to  input  object 

Creates  a reference  (shallow  copy)  to  an  object 


Procedure: 

Parameters: 


Returns: 

Description: 

Errors: 


OBJspecialize 

Object  object  - the  object  to  be  specialized 
Class  class  - new  class  for  object 
Error*  errc  - buffer  for  error  code 
Object  - the  specialized  object 

Specializes  an  object  to  be  an  instance  of  some  subclass  of  its  class.  All  references  to 
the  old  object  will  refer  to  the  new  object 

ERROR_subclass_required  - the  new  class  is  not  a subclass  of  the  object’s 
current  class.  This  error  is  reported  locally,  and  ERROR_subordinate_f  ailed 
is  propagated. 

ERROR_manipulate_constant  - the  object  to  be  specialized  is  a constant. 


4.1.8  Stack 

This  module  implements  the  classic  LIFO  Stack.  It  is  implemented  as  a set  of  macros 
wrapped  around  the  Linked  List  abstraction.  Stacks  may  be  heterogeneous. 


Procedure: 

Parameters: 

Returns: 


STACKempty 

Stack  stack  - the  stack  to  be  tested 
Boolean  - is  the  stack  empty? 
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Procedure: 

STACKiniualize 

Parameters: 

Returns: 

Description: 

— none  — 

void 

Initialize  the  Stack  module. 

Procedure: 

Parameters: 

Returns: 

Requires: 

Description: 

STACKpeek 

Stack  stack  - the  stack  to  peek  at 

Generic  - the  top  item  on  the  stack 
! STACKempty(stack) 

Peeks  at  the  top  of  a stack,  returning  it  without  removing  it  from  the  stack. 

Procedure: 

Parameters: 

Returns: 

Requires: 

Description: 

STACKpop 

Stack  stack  - the  stack  to  pop 

Generic  - the  top  item  on  the  stack 

ISTACKempty(stack) 

Removes  the  top  item  from  a stack  and  returns  it  to  the  caller. 

Procedure: 

Parameters: 

Returns: 

Description: 

STACKpush 

Stack  stack  - the  stack  to  push  onto 

Generic  item  - the  item  to  push 
void 

Pushes  an  item  onto  the  top  of  a stack. 

4.1.9  String 

This  module  defines  macros  and  functions  for  manipulating  C strings.  Some  routines 
provide  special  functionality,  while  others  simply  rename  standard  calls  from  the  C li- 
brary to  fit  the  naming  scheme  of  the  Toolkit.  The  String  type  is  a synonym  for 
char*. 


Procedure: 

STRINGcompare 

Parameters: 

Returns: 

Description: 

String  si  - First  comparison  string 

String  s2  - second  comparison  string 
int  - measure  of  equality  of  strings 

This  is  an  alias  for  the  standard  C call  strcmp  ( ) . The  result  is  0 when  the  two 
arguments  are  equal,  negative  when  si  precedes  s2  in  lexicographical  order,  and 
positive  when  si  follows  s2. 

Procedure: 

Parameters: 

Returns: 

Description: 

STRINGcopy 

String  string  - the  string  to  copy 

String  - a deep  copy  of  the  argument 

Allocates  a String  large  enough  to  hold  the  (NUL-terminated)  argument,  copies  the 
argument  into  this  String,  and  returns  it  to  the  caller. 
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Procedure: 

Parameters: 

Returns: 

Requires: 

Description: 

STRINGcopy_into 

String  dest  - the  destination  string 

String  src-  the  string  to  be  copied 
dest 

STRINGlength(dest)  >=  STRINGlength(src) 

This  is  an  alias  for  the  C library  call  st  rcpy  ( ) . The  source  string  is  copied  into  the 
destination  string,  which  must  be  of  equal  or  greater  length. 

Procedure: 

Parameters: 

Returns: 

STRINGcreate 

int  length  - length  of  string  to  create 

String  - a new,  empty  string  of  at  least  the  given  length 

Procedure: 

Parameters: 

Returns: 

STRINGdowncase_char 
char  c - the  character  to  convert 

char  - the  argument  character,  as  lower  case  if  it  is  a letter 

Procedure: 

Parameters: 

Returns: 

Description: 

STRINGequal 

String  si  - first  string  for  comparison 

String  s2  - second  string  for  comparison 

Boolean  - are  the  two  strings  equal? 

Compares  two  strings  for  value  equality.  This  call  is  equivalent  to  st  rcmp  (si, 
s2 ) ==  0. 

Procedure: 

Parameters: 

Returns: 

Description: 

STRING  free 

String  string  - the  string  to  be  released 
void 

Allows  all  storage  associated  with  a string  to  be  reclaimed.  References  to  the  string 
may  no  longer  be  valid. 

Procedure: 

Parameters: 

Returns: 

Description: 

STRINGlength 

String  string  - the  string  to  measure 

int  - the  actual  length  of  the  suing,  excluding  the  NUL  terminator 

This  call  is  equivalent  to  strlen  (string) . 

Procedure: 

Parameters: 

Returns: 

Description: 

STRINGlowercase 

String  suing  - the  suing  to  convert 

String  - lowercased  version  of  the  argument 

A new  string  is  created  and  returned  which  contains  the  same  value  as  the  argument, 
but  with  all  letters  replaced  with  their  lowercase  counterparts. 

Procedure: 

Parameters: 

Returns: 

Description: 

STRINGsubstring 

String  str  - string  to  extract  a subsuing  from 
int  from  - beginning  index  for  substring 
int  to  - ending  index  for  substring 

Suing  - the  specified  substring 

A new  suing  is  created  and  returned  whose  value  is  a particular  substring  of  some 
string.  The  index  of  the  first  character  of  a string  is  0. 

Procedure: 

Parameters: 

Returns: 

STRINGupcase_char 

char  c - the  character  to  convert 

char  - the  argument  character,  as  upper  case  if  it  is  a letter 
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Procedure: 

STRINGuppercase 

Parameters: 

Returns: 

Description: 

String  string  - the  string  to  convert 

String  - uppercased  version  of  the  argument 

A new  string  is  created  and  returned  which  contains  the  same  value  as  the  argument, 
but  with  all  letters  replaced  with  their  uppercase  counterparts. 

4.1.10  Error  Codes 

This  section  specifies  all  of  the  Errors  which  are  defined  in  libmisc  . a.  Note  that 
each  is  a global  variable;  storage  is  allocated  for  each  by  the  module  named. 


Error: 

HRROR_duplicate_entry 

Defined  In: 
Severity: 
Meaning: 
Format: 

Dicuonary 

SEVERITY_ERROR 

A name  was  duplicated  in  a dictionary 
%s  - the  duplicated  name 

Error: 

Defined  In: 
Severity: 
Meaning: 
Format: 

ERROR_empty_List 

Linked_List 

severity_error 

Illegal  operation  on  an  empty  list 

%s  - the  context  (function)  in  which  the  error  occurred 

Error: 

Defined  In: 
Severity: 
Meaning: 
Format: 

ERROR_free_null_po  inter 

Error 

SEVERITY_DUMP 

A NULL  pom  ter  was  freed 

%s  - the  name  of  the  offending  function 

Error: 

Defined  In: 
Severity: 
Meaning: 
Format: 

ERROR_memory_exhausted 

Error 

SEVERITY_EXIT 

A malloc  (2 ) request  could  not  be  satisfied 
%d  - number  of  bytes  requested 
%s  - intended  use  for  memory 

Error: 

Defined  In: 

Severity: 

Meaning: 

Format: 

ERROR_none 

Error 

N/A 

No  error  occurred.  In  another  life,  this  might  have  been  called  ERROR  NULL.  But 
then,  who  knows?! 

— none  -- 

Error: 

Defined  In: 
Severity: 
Meaning: 
Format: 

ERROR_not_implemented 

Error 

SEVERITY_EXIT 

An  unimplemented  function  was  called. 

%s  - the  name  of  the  function 

The  NIST  PDES  Toolkit:  Technical  Fundamentals 


Page  2 1 


Stephen  Nowland  Clark 


Error: 
Defined  In: 
Severity: 
Meaning: 
Format: 


ERROR_obsolete 

Error 

SEVERITY_W  ARMING 
An  obsolete  function  was  called. 

%s  - the  obsolete  function  name 

%s  - new  name  to  use  OR  reference  to  replacement  code  OR  "<No  Replacement^' 


Error: 
Defined  In: 
Severity: 
Meaning: 

Format: 


ERROR_subordinate_failed 

Error 

SEVERITY_ERROR 

A subordinate  function  has  failed  and  reported  an  error  to  the  user.  Useful  when  the 
caller  only  needs  to  know  that  a problem  has  occurred.  This  error  is  not  reported. 

--  none  - 


4.2  The  Bison  Support  Library:  libbison  . a 

The  Bison  support  library  is  based  on  the  standard  Unix  Yacc  suport  library 
libyacc  . a.,  with  modifications  to  support  better  error  handling/reporting,  imple- 
mentation differences  between  Yacc  and  Bison  (and  also  between  Lex  and  Flex),  and 
more  careful  use  of  global  variables,  this  latter  to  allow  more  than  one  Bison  parser  to 
be  linked  into  a single  executable.  The  library  is  in  '-pdes/lib/libbison  . a,  and 
sources  can  be  found  in  ~pdes/src/libbison/. 

The  definitions  of  yyerror  ( ) in  yyer  ror  . c and  yywhere  ( ) in  yywhere  . c are 
from  [Schreiner85]. 

Several  variable  declarations  in  these  two  files  had  to  be  modifed  for  Bison/Flex  pars- 
ers. A documented  difference  between  Lex  and  Flex  is  that  the  token  buffer,  yytext, 
is  declared  as  a char*  in  Flex  and  as  a char  [ ] in  Lex.  Also,  Flex  does  not  provide 
Lex’s  yy  leng  variable.  Other  variables  which  need  to  be  declared  extern  in  Bison 
parsers  so  as  not  to  collide  when  multiple  parsers  are  linked  together  have  storage  allo- 
cated in  yyvar  s . c.  This  file  also  defines  a function  yynewpar se  ( ) , which  can  be 
used  to  restart  a Bison  parser. 

A word  on  the  ~pdes/etc/uniquify_*  scripts.  These  csh  scripts  modify  the 
code  produced  by  Yacc/Bison/Lex/Flex  so  that  multiple  scanners  and  parsers  can  coex- 
ist in  a single  executable.  For  the  most  part,  it  is  sufficient  to  change  some  global  vari- 
able declarations  to  be  static.  Each  script  strips  any  of  several  suffixes  off  of  the 
filename  it  is  given  to  determine  the  actual  name  of  the  parser/scanner  and  then 
prepends  this  name  to  type  and  function  declarations  which  are  externally  visible. 
Thus,  a parser  called  expyacc  . y ends  up  with  the  entry  point  exp_yyparse  0,  ex- 
pects tokens  of  type  exp_YYSTYPE,  and  calls  exp_yylex  ( ) to  get  these  tokens. 
Similarly,  a scanner  called  stepscan  . 1 would  provide  step_yylex  ( ) as  an  entry 
point,  and  would  produce  tokens  of  type  step_YYSTYPE. 
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4.3  BSD  Unix  Dynamic  Loading:  libdyna  . a 

This  package  was  retrieved  from  the  Internet.  Authorship  information  seems  to  have 
been  lost.  The  routines  provided  are  at  the  level  of  reading  a . out  headers  and  walking 
through  symbol  tables.  We  will  not  attempt  to  document  this  library,  there  are  . doc 
files  in  the  source  directory,  ~pdes/src/  libdyna/,  which  include  examples  of  the 
package’s  use. 
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B The  Makefile  Template 

# 

# This  is  a Makefile  template  for  translators  and  other  applications 

# which  use  the  Express  and/or  STEP  Working  Forms  from  the  NIST  PDES 

# Toolkit . 

# 

# This  software  was  developed  by  U.S.  Government  employees  as  part  of 

# their  official  duties  and  is  not  subject  to  copyright. 

# 

# Pick  up  default  macros  and  rules 
include  . . / . . /include/make_rules 

#########*########*############# 

# Pick  a C compiler  ...  any  C compiler! 
################################ 

#CC  = $ (Unix_CC) 

CC  = $ (GCC ) 

####*########################### 

# User-definable  flags  to  CC : 

# Put  whatever  you  want  in  here! 

################################ 

#MY_C FLAGS  = -g  -0 
MY_C FLAGS  = -g 

############################*### 

# CC  flags  for  Express  and  STEP 

# 

# Use  the  first  form  for  STEP  applications. 

# Use  the  second  if  only  Express  is  required. 
################################ 

CFLAGS  = $ (STEP_CFLAGS)  $(MY_CFLAGS) 

#CFLAGS  = $ (EXPRESS_CFLAGS)  $ (MY_CFLAGS ) 

################################ 

# Default  rule  to  compile  C source  files 

# 

# You  probably  shouldn't  need  to  change  this  ... 
################################ 

# . c . o : 

# $(CC)  $ (CFLAGS)  -c  $*.c 

################################################################ 

# 

# Library  Selection 

# 

# Select  the  first  one  of  the  following  forms  which  describes  your 

# application.  For  further  discussion,  see  "The  NIST  PDES  Toolkit: 

# Technical  Fundamentals." 

# 

################################################################ 

################################ 

# STEPparse  translators/applications: 

# with  statically  bound  report  generators 

#LIBS  = $ (STEP  LIBS) 
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# with  dynamically  bound  report  generators 

#LIBS  = $ (PDESLIBDIR) step_dynamic . o $(STEP_LIBS)  -ldyna 

################################ 

# Fed-X  Express  translators/applications: 

# with  statically  bound  report  generators 
#LIBS  = $ (EXPRESS_LIBS) 

# with  dynamically  bound  report  generators 

#LIBS  = $ (PDESLIBDIR) expres s_dynamic . o $ (EXPRESS_LIBS ) -ldyna 
################################ 

# STEP  applications  with  Express  report  generators 

# statically  bound 
#LIBS  = $ ( STEP_LIBS ) 

# dynamically  bound 

#LIBS  = $ (PDESLIBDIR) express_dynamic . o $(STEP_LIBS)  -ldyna 

################################ 

# STEP  application  with  no  report  generators 

#LIBS  = $ ( STEP_LIBS ) 

################################ 

# Pure  Express  application  with  no  report  generators 
#LIBS  = $ (EXPRESS_LIBS) 

#######################################################*####**## 

# List  all  of  your  object  files  here.  If  you  are  building  a 

# translator  which  will  dynamically  load  its  report  generators, 

# do  not  list  any  output  modules  here. 
##########################################################*##*** 

# Object  files  for  Fed-X  or  STEPparse  translator  with  dynamically 

# loaded  report  generators 
#OFILES  = 

# Object  files  for  STEPparse  translator  with  STEP  report 

# generator  statically  loaded 
#OFILES  = step_output_step . o 

# Object  files  for  Fed-X  translator  with  Smalltalk-80  report 

# generator  statically  loaded 
#OFILES  = output_smalltalk . o 

*############################################################### 

# List  all  of  your  libraries  here 
#############################################################*## 

MYLIBS  = 

###########################################################*#### 

# The  name  of  the  executable  to  build 
################################################################ 

PROG  = 

################################################################ 

# Here's  the  rule  that  builds  the  executable. 
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############################################*################### 


$ (PROG) : 

$ (OFILES) 

$(CC)  $ (CFLAGS ) 

-o  $ (PROG) 

$ (OFILES) 

$ (LIBS) 

$ (MYLIBS ) 

relink : 

5 (CC)  $ (CFLAGS) 

-o  $ (PROG) 

$ (OFILES) 

$ (LIBS) 

$ (MYLIBS) 

install 


cp  $ (PROG)  $ (PDESBINDIR) 


clean : 


rm  -f  $ (OFILES ) $ (PROG)  #* 

################################################################ 
# Put  any  rules  for  building  your  object  files  here. 
#############################################################*## 
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